…ic#263617)

## Summary

This PR is a housekeeping pass on the public API documentation for
Kibana Cases. The docs had drifted from reality — some fields were
missing, some examples were wrong, some endpoints had no code samples,
and the docs validator was throwing 22 errors. This PR makes the docs
match what the API actually returns, and gets the validator to pass
cleanly.

Nothing about the API itself changes. Only documentation and its
generated bundles.

## The four kinds of fixes

### 1. Added missing "unauthorized" (401) examples

Every Cases endpoint was missing an example for its 401 response, which
tripped the validator. Rather than copy-pasting the same example 16
times, a shared `components/examples/response_401.yaml` was created and
referenced everywhere. One endpoint
(`paths/api@cases@alerts@{alertid}.yaml`) was also using a deprecated
`example:` format and got converted to the modern `examples:` map.

### 2. Filled in missing code samples and request examples

Four endpoints gained curl + Console code samples or request-body
examples — most notably:

- **File upload** (`paths/api@cases@{caseid}@files.yaml`) — now shows
multipart form usage
- **Push-to-connector**
(`paths/api@cases@{caseid}@connector@{connectorid}@_push.yaml`) —
clarified that no body is needed
- **Delete comments** (both bulk and single) — added curl + Console
samples

Five query-parameter component files also got `example:` values so the
rendered docs aren't blank:

- `page_index.yaml` → `1`
- `page_size.yaml` → `20`
- `sort_order.yaml` → `desc`
- `severity.yaml` → `low`
- `search.yaml` → `Case title 1`

### 3. Schema inaccuracies — docs didn't match reality

Three notable gaps between docs and actual API responses:

- **`incremental_id` on cases** — added to
`case_response_properties.yaml` and `case_response_get_case.yaml`, with
a note that it's populated asynchronously and won't appear in the
immediate `POST` response.
- **User-action `type` enum was stale** — had 11 values, should have had
16. Added `category`, `customFields`, `delete_case`, `extended_fields`,
`observables` to `user_actions_find_response_properties.yaml`.
- **`observableTypes` was completely missing** from the
case-configuration response schema — added to
`case_configure_response_properties.yaml`.

### 4. Example payloads didn't match real API output

Author tested example files against a live Kibana and patched
discrepancies:

- **`add_comment_response.yaml`** — was missing `pushed_at`,
`pushed_by`, `updated_at`, `updated_by`, and `profile_uid` on
`created_by`.
- **`push_case_response.yaml`** — was missing `assignees`,
`customFields`, `category`, and `profile_uid` on
`created_by`/`updated_by`.

## Why the diff looks huge (+41,888 / −84,370)

Don't be alarmed by the size. The vast majority of the churn is in three
regenerated files:

- `oas_docs/output/kibana.yaml` (+40,991 / −84,137)
- `x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.json`
-
`x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.schema.yaml`

These are machine-generated bundles. A manual post-bundle fixup was
applied to the schema YAML to convert Redocly's file-path discriminator
mappings (`foo.yaml`) into the `#/components/schemas/foo` format that
`kbn-openapi-bundler` requires, so that `make merge-api-docs-stateful`
continues to work.

## Key files to actually review

The hand-written changes (everything non-generated) are concentrated in:

- `components/examples/` — new shared 401 example + updated response
examples
- `components/parameters/` — added example values
- `components/schemas/` — the three schema fixes
- `paths/` — 16 path files got the 401 reference; a handful got new code
samples

## Bottom line

Docs-only cleanup. No runtime behavior changes, no tests to run, just
safer and more accurate public API documentation. Validator now passes
with **0 errors**.

- written with Claude

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

…263617) (#265404)

# Backport

This will backport the following commits from `main` to `9.4`:
- [[Cases][Docs] - Add additional examples and cleanup to openApi
(#263617)](#263617)

<!--- Backport version: 11.0.2 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Michael
Olorunnisola","email":"michael.olorunnisola@elastic.co"},"sourceCommit":{"committedDate":"2026-04-22T16:50:30Z","message":"[Cases][Docs]
- Add additional examples and cleanup to openApi (#263617)\n\n##
Summary\n\nThis PR is a housekeeping pass on the public API
documentation for\nKibana Cases. The docs had drifted from reality —
some fields were\nmissing, some examples were wrong, some endpoints had
no code samples,\nand the docs validator was throwing 22 errors. This PR
makes the docs\nmatch what the API actually returns, and gets the
validator to pass\ncleanly.\n\nNothing about the API itself changes.
Only documentation and its\ngenerated bundles.\n\n## The four kinds of
fixes\n\n### 1. Added missing \"unauthorized\" (401) examples\n\nEvery
Cases endpoint was missing an example for its 401 response,
which\ntripped the validator. Rather than copy-pasting the same example
16\ntimes, a shared `components/examples/response_401.yaml` was created
and\nreferenced everywhere. One
endpoint\n(`paths/api@cases@alerts@{alertid}.yaml`) was also using a
deprecated\n`example:` format and got converted to the modern
`examples:` map.\n\n### 2. Filled in missing code samples and request
examples\n\nFour endpoints gained curl + Console code samples or
request-body\nexamples — most notably:\n\n- **File upload**
(`paths/api@cases@{caseid}@files.yaml`) — now shows\nmultipart form
usage\n-
**Push-to-connector**\n(`paths/api@cases@{caseid}@connector@{connectorid}@_push.yaml`)
—\nclarified that no body is needed\n- **Delete comments** (both bulk
and single) — added curl + Console\nsamples\n\nFive query-parameter
component files also got `example:` values so the\nrendered docs aren't
blank:\n\n- `page_index.yaml` → `1`\n- `page_size.yaml` → `20`\n-
`sort_order.yaml` → `desc`\n- `severity.yaml` → `low`\n- `search.yaml` →
`Case title 1`\n\n### 3. Schema inaccuracies — docs didn't match
reality\n\nThree notable gaps between docs and actual API
responses:\n\n- **`incremental_id` on cases** — added
to\n`case_response_properties.yaml` and `case_response_get_case.yaml`,
with\na note that it's populated asynchronously and won't appear in
the\nimmediate `POST` response.\n- **User-action `type` enum was stale**
— had 11 values, should have had\n16. Added `category`, `customFields`,
`delete_case`, `extended_fields`,\n`observables` to
`user_actions_find_response_properties.yaml`.\n- **`observableTypes` was
completely missing** from the\ncase-configuration response schema —
added to\n`case_configure_response_properties.yaml`.\n\n### 4. Example
payloads didn't match real API output\n\nAuthor tested example files
against a live Kibana and patched\ndiscrepancies:\n\n-
**`add_comment_response.yaml`** — was missing `pushed_at`,\n`pushed_by`,
`updated_at`, `updated_by`, and `profile_uid` on\n`created_by`.\n-
**`push_case_response.yaml`** — was missing
`assignees`,\n`customFields`, `category`, and `profile_uid`
on\n`created_by`/`updated_by`.\n\n## Why the diff looks huge (+41,888 /
−84,370)\n\nDon't be alarmed by the size. The vast majority of the churn
is in three\nregenerated files:\n\n- `oas_docs/output/kibana.yaml`
(+40,991 / −84,137)\n-
`x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.json`\n-\n`x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.schema.yaml`\n\nThese
are machine-generated bundles. A manual post-bundle fixup was\napplied
to the schema YAML to convert Redocly's file-path
discriminator\nmappings (`foo.yaml`) into the `#/components/schemas/foo`
format that\n`kbn-openapi-bundler` requires, so that `make
merge-api-docs-stateful`\ncontinues to work.\n\n## Key files to actually
review\n\nThe hand-written changes (everything non-generated) are
concentrated in:\n\n- `components/examples/` — new shared 401 example +
updated response\nexamples\n- `components/parameters/` — added example
values\n- `components/schemas/` — the three schema fixes\n- `paths/` —
16 path files got the 401 reference; a handful got new
code\nsamples\n\n## Bottom line\n\nDocs-only cleanup. No runtime
behavior changes, no tests to run, just\nsafer and more accurate public
API documentation. Validator now passes\nwith **0 errors**.\n\n- written
with Claude\n\n---------\n\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"61a520d49e389557c908761e231f74eac9d1dcaf","branchLabelMapping":{"^v9.5.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","backport
missing","backport:version","Team:Cases","v9.4.0","v9.5.0","v9.3.4"],"title":"[Cases][Docs]
- Add additional examples and cleanup to
openApi","number":263617,"url":"https://github.com/elastic/kibana/pull/263617","mergeCommit":{"message":"[Cases][Docs]
- Add additional examples and cleanup to openApi (#263617)\n\n##
Summary\n\nThis PR is a housekeeping pass on the public API
documentation for\nKibana Cases. The docs had drifted from reality —
some fields were\nmissing, some examples were wrong, some endpoints had
no code samples,\nand the docs validator was throwing 22 errors. This PR
makes the docs\nmatch what the API actually returns, and gets the
validator to pass\ncleanly.\n\nNothing about the API itself changes.
Only documentation and its\ngenerated bundles.\n\n## The four kinds of
fixes\n\n### 1. Added missing \"unauthorized\" (401) examples\n\nEvery
Cases endpoint was missing an example for its 401 response,
which\ntripped the validator. Rather than copy-pasting the same example
16\ntimes, a shared `components/examples/response_401.yaml` was created
and\nreferenced everywhere. One
endpoint\n(`paths/api@cases@alerts@{alertid}.yaml`) was also using a
deprecated\n`example:` format and got converted to the modern
`examples:` map.\n\n### 2. Filled in missing code samples and request
examples\n\nFour endpoints gained curl + Console code samples or
request-body\nexamples — most notably:\n\n- **File upload**
(`paths/api@cases@{caseid}@files.yaml`) — now shows\nmultipart form
usage\n-
**Push-to-connector**\n(`paths/api@cases@{caseid}@connector@{connectorid}@_push.yaml`)
—\nclarified that no body is needed\n- **Delete comments** (both bulk
and single) — added curl + Console\nsamples\n\nFive query-parameter
component files also got `example:` values so the\nrendered docs aren't
blank:\n\n- `page_index.yaml` → `1`\n- `page_size.yaml` → `20`\n-
`sort_order.yaml` → `desc`\n- `severity.yaml` → `low`\n- `search.yaml` →
`Case title 1`\n\n### 3. Schema inaccuracies — docs didn't match
reality\n\nThree notable gaps between docs and actual API
responses:\n\n- **`incremental_id` on cases** — added
to\n`case_response_properties.yaml` and `case_response_get_case.yaml`,
with\na note that it's populated asynchronously and won't appear in
the\nimmediate `POST` response.\n- **User-action `type` enum was stale**
— had 11 values, should have had\n16. Added `category`, `customFields`,
`delete_case`, `extended_fields`,\n`observables` to
`user_actions_find_response_properties.yaml`.\n- **`observableTypes` was
completely missing** from the\ncase-configuration response schema —
added to\n`case_configure_response_properties.yaml`.\n\n### 4. Example
payloads didn't match real API output\n\nAuthor tested example files
against a live Kibana and patched\ndiscrepancies:\n\n-
**`add_comment_response.yaml`** — was missing `pushed_at`,\n`pushed_by`,
`updated_at`, `updated_by`, and `profile_uid` on\n`created_by`.\n-
**`push_case_response.yaml`** — was missing
`assignees`,\n`customFields`, `category`, and `profile_uid`
on\n`created_by`/`updated_by`.\n\n## Why the diff looks huge (+41,888 /
−84,370)\n\nDon't be alarmed by the size. The vast majority of the churn
is in three\nregenerated files:\n\n- `oas_docs/output/kibana.yaml`
(+40,991 / −84,137)\n-
`x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.json`\n-\n`x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.schema.yaml`\n\nThese
are machine-generated bundles. A manual post-bundle fixup was\napplied
to the schema YAML to convert Redocly's file-path
discriminator\nmappings (`foo.yaml`) into the `#/components/schemas/foo`
format that\n`kbn-openapi-bundler` requires, so that `make
merge-api-docs-stateful`\ncontinues to work.\n\n## Key files to actually
review\n\nThe hand-written changes (everything non-generated) are
concentrated in:\n\n- `components/examples/` — new shared 401 example +
updated response\nexamples\n- `components/parameters/` — added example
values\n- `components/schemas/` — the three schema fixes\n- `paths/` —
16 path files got the 401 reference; a handful got new
code\nsamples\n\n## Bottom line\n\nDocs-only cleanup. No runtime
behavior changes, no tests to run, just\nsafer and more accurate public
API documentation. Validator now passes\nwith **0 errors**.\n\n- written
with Claude\n\n---------\n\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"61a520d49e389557c908761e231f74eac9d1dcaf"}},"sourceBranch":"main","suggestedTargetBranches":["9.4","9.3"],"targetPullRequestStates":[{"branch":"9.4","label":"v9.4.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.5.0","branchLabelMappingKey":"^v9.5.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/263617","number":263617,"mergeCommit":{"message":"[Cases][Docs]
- Add additional examples and cleanup to openApi (#263617)\n\n##
Summary\n\nThis PR is a housekeeping pass on the public API
documentation for\nKibana Cases. The docs had drifted from reality —
some fields were\nmissing, some examples were wrong, some endpoints had
no code samples,\nand the docs validator was throwing 22 errors. This PR
makes the docs\nmatch what the API actually returns, and gets the
validator to pass\ncleanly.\n\nNothing about the API itself changes.
Only documentation and its\ngenerated bundles.\n\n## The four kinds of
fixes\n\n### 1. Added missing \"unauthorized\" (401) examples\n\nEvery
Cases endpoint was missing an example for its 401 response,
which\ntripped the validator. Rather than copy-pasting the same example
16\ntimes, a shared `components/examples/response_401.yaml` was created
and\nreferenced everywhere. One
endpoint\n(`paths/api@cases@alerts@{alertid}.yaml`) was also using a
deprecated\n`example:` format and got converted to the modern
`examples:` map.\n\n### 2. Filled in missing code samples and request
examples\n\nFour endpoints gained curl + Console code samples or
request-body\nexamples — most notably:\n\n- **File upload**
(`paths/api@cases@{caseid}@files.yaml`) — now shows\nmultipart form
usage\n-
**Push-to-connector**\n(`paths/api@cases@{caseid}@connector@{connectorid}@_push.yaml`)
—\nclarified that no body is needed\n- **Delete comments** (both bulk
and single) — added curl + Console\nsamples\n\nFive query-parameter
component files also got `example:` values so the\nrendered docs aren't
blank:\n\n- `page_index.yaml` → `1`\n- `page_size.yaml` → `20`\n-
`sort_order.yaml` → `desc`\n- `severity.yaml` → `low`\n- `search.yaml` →
`Case title 1`\n\n### 3. Schema inaccuracies — docs didn't match
reality\n\nThree notable gaps between docs and actual API
responses:\n\n- **`incremental_id` on cases** — added
to\n`case_response_properties.yaml` and `case_response_get_case.yaml`,
with\na note that it's populated asynchronously and won't appear in
the\nimmediate `POST` response.\n- **User-action `type` enum was stale**
— had 11 values, should have had\n16. Added `category`, `customFields`,
`delete_case`, `extended_fields`,\n`observables` to
`user_actions_find_response_properties.yaml`.\n- **`observableTypes` was
completely missing** from the\ncase-configuration response schema —
added to\n`case_configure_response_properties.yaml`.\n\n### 4. Example
payloads didn't match real API output\n\nAuthor tested example files
against a live Kibana and patched\ndiscrepancies:\n\n-
**`add_comment_response.yaml`** — was missing `pushed_at`,\n`pushed_by`,
`updated_at`, `updated_by`, and `profile_uid` on\n`created_by`.\n-
**`push_case_response.yaml`** — was missing
`assignees`,\n`customFields`, `category`, and `profile_uid`
on\n`created_by`/`updated_by`.\n\n## Why the diff looks huge (+41,888 /
−84,370)\n\nDon't be alarmed by the size. The vast majority of the churn
is in three\nregenerated files:\n\n- `oas_docs/output/kibana.yaml`
(+40,991 / −84,137)\n-
`x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.json`\n-\n`x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.schema.yaml`\n\nThese
are machine-generated bundles. A manual post-bundle fixup was\napplied
to the schema YAML to convert Redocly's file-path
discriminator\nmappings (`foo.yaml`) into the `#/components/schemas/foo`
format that\n`kbn-openapi-bundler` requires, so that `make
merge-api-docs-stateful`\ncontinues to work.\n\n## Key files to actually
review\n\nThe hand-written changes (everything non-generated) are
concentrated in:\n\n- `components/examples/` — new shared 401 example +
updated response\nexamples\n- `components/parameters/` — added example
values\n- `components/schemas/` — the three schema fixes\n- `paths/` —
16 path files got the 401 reference; a handful got new
code\nsamples\n\n## Bottom line\n\nDocs-only cleanup. No runtime
behavior changes, no tests to run, just\nsafer and more accurate public
API documentation. Validator now passes\nwith **0 errors**.\n\n- written
with Claude\n\n---------\n\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"61a520d49e389557c908761e231f74eac9d1dcaf"}},{"branch":"9.3","label":"v9.3.4","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

---------

Co-authored-by: Michael Olorunnisola <michael.olorunnisola@elastic.co>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

…ic#263617)

## Summary

This PR is a housekeeping pass on the public API documentation for
Kibana Cases. The docs had drifted from reality — some fields were
missing, some examples were wrong, some endpoints had no code samples,
and the docs validator was throwing 22 errors. This PR makes the docs
match what the API actually returns, and gets the validator to pass
cleanly.

Nothing about the API itself changes. Only documentation and its
generated bundles.

## The four kinds of fixes

### 1. Added missing "unauthorized" (401) examples

Every Cases endpoint was missing an example for its 401 response, which
tripped the validator. Rather than copy-pasting the same example 16
times, a shared `components/examples/response_401.yaml` was created and
referenced everywhere. One endpoint
(`paths/api@cases@alerts@{alertid}.yaml`) was also using a deprecated
`example:` format and got converted to the modern `examples:` map.

### 2. Filled in missing code samples and request examples

Four endpoints gained curl + Console code samples or request-body
examples — most notably:

- **File upload** (`paths/api@cases@{caseid}@files.yaml`) — now shows
multipart form usage
- **Push-to-connector**
(`paths/api@cases@{caseid}@connector@{connectorid}@_push.yaml`) —
clarified that no body is needed
- **Delete comments** (both bulk and single) — added curl + Console
samples

Five query-parameter component files also got `example:` values so the
rendered docs aren't blank:

- `page_index.yaml` → `1`
- `page_size.yaml` → `20`
- `sort_order.yaml` → `desc`
- `severity.yaml` → `low`
- `search.yaml` → `Case title 1`

### 3. Schema inaccuracies — docs didn't match reality

Three notable gaps between docs and actual API responses:

- **`incremental_id` on cases** — added to
`case_response_properties.yaml` and `case_response_get_case.yaml`, with
a note that it's populated asynchronously and won't appear in the
immediate `POST` response.
- **User-action `type` enum was stale** — had 11 values, should have had
16. Added `category`, `customFields`, `delete_case`, `extended_fields`,
`observables` to `user_actions_find_response_properties.yaml`.
- **`observableTypes` was completely missing** from the
case-configuration response schema — added to
`case_configure_response_properties.yaml`.

### 4. Example payloads didn't match real API output

Author tested example files against a live Kibana and patched
discrepancies:

- **`add_comment_response.yaml`** — was missing `pushed_at`,
`pushed_by`, `updated_at`, `updated_by`, and `profile_uid` on
`created_by`.
- **`push_case_response.yaml`** — was missing `assignees`,
`customFields`, `category`, and `profile_uid` on
`created_by`/`updated_by`.

## Why the diff looks huge (+41,888 / −84,370)

Don't be alarmed by the size. The vast majority of the churn is in three
regenerated files:

- `oas_docs/output/kibana.yaml` (+40,991 / −84,137)
- `x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.json`
-
`x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.schema.yaml`

These are machine-generated bundles. A manual post-bundle fixup was
applied to the schema YAML to convert Redocly's file-path discriminator
mappings (`foo.yaml`) into the `#/components/schemas/foo` format that
`kbn-openapi-bundler` requires, so that `make merge-api-docs-stateful`
continues to work.

## Key files to actually review

The hand-written changes (everything non-generated) are concentrated in:

- `components/examples/` — new shared 401 example + updated response
examples
- `components/parameters/` — added example values
- `components/schemas/` — the three schema fixes
- `paths/` — 16 path files got the 401 reference; a handful got new code
samples

## Bottom line

Docs-only cleanup. No runtime behavior changes, no tests to run, just
safer and more accurate public API documentation. Validator now passes
with **0 errors**.

- written with Claude

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>